#region Terms of Usage
/*
 * Copyright 2006 Sameera Perera
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */
#endregion

using System;
using System.Collections.Generic;
using System.Text;

namespace needle.Services.soab.RequestQueue
{
    /// <summary>
    /// Interface implemented by <see cref="ServiceRequest.Payload"/> objects that require
    /// other cached items to be updated via online function calls, before they themselvs
    /// can be transfered to the server.
    /// </summary>
        /// <example>
        /// In the following example, in order to save the <c>book</c> object is dependant
        /// on the <c>author</c> object. This would effectively mean that (due to resons
        /// such as foreign key constraints etc.) before the <c>book</c> can be saved to the
        /// server database, <c>author</c> should already be present in the same database.
        /// Therefore, the class Book should implement ICacheDependant with 
        /// <see cref="ICacheDependant.ResolutionDepth"/> returning 2 and 
        /// <see cref="ICacheDependant.IsResolved"/> returning true when the <see cref="Book.Author.ID"/> is 
        /// greater than zero.
        /// <code>
        /// class Author {
        ///     private int id = 0;
        ///     // The Author-ID corresponds to an auto incrementing positive integer value
        ///     // which is the primary key of the Author table on the server's database.
        ///     public int ID { get { return this.id; } set { this.id = value; } }
        /// }
        /// 
        /// class Book { 
        ///     private author = null;
        ///     public Author { get { return this.author; } set { this.author = value; } }
        /// }
        /// 
        /// static void Main(){
        ///     Book book     = new Book();
        ///     Author author = new Author();
        ///     book.Author   = author;
        /// 
        ///     // ...
        /// }
        /// </code>
        /// </example>
    public interface ICacheDependant
    {
        /// <summary>
        /// Gets the the number of levels to which the payload object should be refreshed
        /// in order to ensure that the dependancy could be correctly resolved.
        /// </summary>
        /// <example>
        /// In the Book-Author example <see cref="ICacheDependant"/> this would be 2, as to
        /// resolve whether the author object has been updated, two levels of the object heirarchy
        /// (level 1:- book, level 2:- book.Author) have to be refreshed.
        /// </example>
        int ResolutionDepth { get; }
        /// <summary>
        /// Gets whether the dependancy has been resolved.
        /// </summary>
        bool IsResolved { get; }
    }
}
